…he()

createEloquentProvider() now calls $provider->enableCache() when the
cache config block has enabled=true. Passes the store NAME (nullable;
null = default store), TTL, and prefix straight through — the provider
re-resolves the store by name on invalidation, so no pre-resolved
repository is held at this layer.

No change to the database provider path.

Exposes a guard-scoped wrapper around EloquentUserProvider::clearUserCache()
for apps that need to invalidate cached user entries from write paths
that bypass Eloquent model events — pivot-table writes for roles and
permissions, mass update() / raw DB queries, queue jobs, external
processes, etc.

Signature: clearUserCache(mixed $identifier, ?string $guard = null): void

Behaviour:
 - Omitted $guard uses the default guard.
 - Resolves the guard's existing provider via getProvider() instead of
   constructing a throwaway one.
 - No-op when the guard doesn't expose getProvider() (custom guards that
   don't use GuardHelpers — checked via method_exists to avoid hitting
   AuthManager::__call and triggering BadMethodCallException at runtime).
 - No-op when the provider isn't an EloquentUserProvider or caching is
   disabled.

The provider's key resolver (if set) runs, so in a tenant-aware setup
this clears the entry for the current tenant context.

Adds the @method static docblock entry for Auth::clearUserCache() next
to resolveUsersUsing so IDEs autocomplete and phpstan understands the
call through the facade.

Adds the per-provider 'cache' block to the default 'users' provider:

    'cache' => [
        'enabled' => env('AUTH_USERS_CACHE_ENABLED', false),
        'store'   => env('AUTH_USERS_CACHE_STORE'),
        'ttl'     => env('AUTH_USERS_CACHE_TTL', 300),
        'prefix'  => env('AUTH_USERS_CACHE_PREFIX', 'auth_users'),
    ],

Disabled by default; a single env flip turns it on. The block is
preceded by a prescriptive docblock listing supported stores (redis,
database, file, swoole, stack), rejected stores (array, null, session,
failover), cross-node behaviour (fully-shared vs node-local vs
stack microcaching), and the recommended high-scale topology
(stack = [swoole L1 → redis L2]). Full rationale lives in the auth
caching documentation; the config comment stays short and prescriptive.

Testbench's auth.providers.users wholly replaces the framework's users
entry during config merge (the merge is one level deep on 'providers',
not recursive), so any key we want present at runtime needs to be
repeated here — including the new 'cache' block.

Same shape and same docblock as the framework config. Disabled by
default, so this change is purely discoverability/consistency for
testbench-bootstrapped test suites and skeletons cloned from testbench.

Adds a new 'User Lookup Cache' section to the auth package README
covering:

 - Purpose: opt-in cross-request cache for retrieveById() to eliminate
   one DB query per authenticated request under Swoole.
 - Config examples: minimum Redis setup and the high-scale stack
   (swoole L1 + redis L2) setup.
 - Microcaching rationale: what it is, why it matters at scale, and the
   concrete wins (p99 latency, Redis tier sizing, bandwidth, resilience
   during brief Redis outages).
 - Invalidation model: four layers (provider writes via save(), model
   events, manual Auth::clearUserCache, TTL), with explicit notes on
   same-node propagation via Swoole Table and bounded cross-node
   staleness when using a stack with a node-local L1.
 - Manual invalidation API: full parameter semantics, how the model
   is chosen from the guard, multi-guard / multi-model behaviour
   (one-provider-shared-by-many-guards vs different-model-per-guard),
   tenant-resolver interaction, and no-op conditions.
 - TTL guidance per scenario.
 - Store selection guide mirroring the config docblock.
 - Tenant-aware cache keys with the resolveUserCacheKeyUsing() pattern
   and why it has to be a static callback, not a config closure.
 - Gotchas: withQuery caching effect, mass-update event bypass, outer-
   only stack validation.
 - Threat-model notes for high-security providers.

Marked with a @todo so the whole section can be lifted into the 0.4
documentation site once it lands — the README is just the interim home.

…scriber

Resets the provider's static state (the cache key resolver, descriptor
registry, and listener-registered flag) between tests so cache-related
tests are isolated from each other.

Placed alphabetically between AuthenticationException::flushState() and
Middleware\Authenticate::flushState().

New dedicated test class kept separate from AuthEloquentUserProviderTest
so the base-provider coverage stays focused and the caching feature
gets its own home.

Covers, with Mockery doubles only (no container, no DB, no dispatcher):

 - Cache disabled: retrieveById falls through to the DB path with no
   cache interaction.
 - Basic operation: miss → DB → put, hit → no DB, missing-user null
   sentinel stored on miss, null returned on sentinel hit.
 - retrieveByCredentials and retrieveByToken never touch the cache.
 - Key format: default {prefix}:{FQCN}:{id}, null/'' prefix normalizes
   to the feature default, custom resolver used for the identifier
   segment, custom resolver receives the raw identifier, FQCN always
   present in the key even with a custom resolver.
 - Supported-store whitelist (data provider over Redis/Database/File/
   Swoole/Stack): enableCache accepts each.
 - Unsupported-store rejection (data provider over Array/Null/Session/
   Failover): enableCache throws InvalidArgumentException.
 - Validation-failure ordering: after a rejected store, the provider
   is still disabled, the descriptor registry is empty, the
   events-registered flag is untouched, and retrieveById falls through
   to the DB path — confirms 'validate before mutate'.
 - Manual clearUserCache: forgets the right key, respects the custom
   resolver, no-op when caching is disabled.
 - flushState resets the resolver, descriptor registry, and
   events-registered flag.

Uses a stub Model subclass (EloquentCacheProviderUserStub) because the
registerCacheInvalidationEvents() path touches ::getEventDispatcher()
on the model class, which needs a real class to resolve.

New Testbench-based integration suite covering the paths that need a
real event dispatcher and a real Model class (things the unit suite
can't exercise). The cache repository itself is still a Mockery double
so forget() calls are verifiable — what matters here is the real
saved/deleted event firing, not the cache backend.

Covers:

 - Cache is cleared on user save.
 - Cache is cleared on user delete.
 - Identical (store, prefix, modelSegment) configs dedupe in the
   descriptor registry.
 - Two distinct (store, prefix) configs for the same model each get
   invalidated on a single save — the listener attaches once, iterates
   both descriptors, fires exactly one forget() per descriptor (guards
   against accidental double-attach).
 - updateRememberToken and rehashPasswordIfRequired clear the cache
   via the saved event — no explicit clear inside the methods.
 - enableCache skips listener registration when the model has no
   dispatcher yet, leaves the events-registered flag unset so a later
   enableCache() call retries, but still registers the descriptor.
 - withQuery compatibility: the withQuery callback runs only on the
   cache-miss fetch; subsequent calls hit the cache.

Uses Hypervel\Foundation\Auth\User (via #[WithMigration] + RefreshDatabase)
so the model is a real Eloquent User with dispatch set up by the
framework boot.

Adds four tests exercising the clearUserCache() convenience method end
to end through the manager + provider + cache stack (cache manager
stubbed via Container::instance, repository + store as Mockery doubles):

 - Custom guard without getProvider() — method_exists guard kicks in,
   call is a no-op, no BadMethodCallException from __call forwarding.
 - Specified guard uses that guard's provider/model — clearing user 42
   on the 'admin' guard forgets AuthManagerCacheAdminStub:42 (not
   AuthManagerCacheUserStub:42), proving the guard determines the
   provider which determines the model.
 - Default guard + custom resolver — clearUserCache with no guard name
   uses the default guard's provider, and the key resolver runs so the
   forget key is the tenant-scoped one, not the raw id.
 - forgetGuards() + re-resolve does not accumulate provider descriptors:
   after forgetting the guard cache and re-resolving, the descriptor
   registry still has exactly one entry for the model. Guards against a
   potential leak where repeated resolve/forget cycles would grow the
   registry.

Stub classes (AuthManagerCacheUserStub / AuthManagerCacheAdminStub)
extend Foundation\Auth\User so getAuthIdentifier() and the model
dispatcher behaviour are real.